-------------------------------------
*  AudioZap 2.0 Extra Specification *
-------------------------------------

Specification revision F.
For AudioZap version 2.0 Freeware Release.
	
Written By Ian Schmidt
Copyright (c) 1990-98 Ian Schmidt.
All Rights Reserved.

NOTE: Extras may or may not actually be able to save files - I don't think this has ever been tested if the functionality DOES exist at all.  Do not get your hopes up on writing an Extra that can :)
	
Changes in this document since AZ 2.0b10: Added new stuff avalible in 2.0b15,
including the ability of a FileTypeParser Extra to save.  NOTE important
change to request procedure name.

| Note: text set off with bars like this indicates functions which are not
| implemented in 2.0b15 or the Freeware Release.
|

Physical Considerations
-----------------------

AZ Extras will normally be GS/OS OMF load files of type EXE ($B5) residing in a
subdirectory called "AZExtras" which itself is in the same directory as the
AudioZap application.  The Extra must begin with a dispatcher routine (details
below).  The Extra when called is given AudioZap's stack and direct page:
the Extra must not change any direct page location unless it is specifically
allowed to.  If you need your own stack/direct page you are provided with a
user ID for this purpose.  Note that AZ Extras can also be in INITs and
use _AcceptRequests and _SendRequest to determine when AZ has been loaded
and have AZ install them as if they were in AZExtras/.  More details are
included later in this document.

Implementation Restrictions
---------------------------

Under AudioZap 2.0, there may be up to 64 Extras installed with 128 total
menu items belonging to Extras.  Extras may insert items into the Format menu,
however they will not be used as save formats. The Extra spec will be revised
from time to time, so be sure you keep all reserved flag bits set to 0 or you
may get calls you don't know how to deal with.

Coding Considerations
---------------------

The stack upon entry to your dispatcher will be formatted as follows:


   |               |
   |---------------|
   | Space         |  LONG - space for result (if any)
12 |               |
   |---------------|
   | Data1         |  LONG - input data (if needed)
 8 |               |
   |---------------|
 6 | UserID        |  WORD - your user ID
   |---------------|
 4 | CallNumber    |  WORD - call number to perform
   |---------------|
 1 |  RTL^3        |  3 BYTES - RTL address


Upon exit the stack must look like this:

   |               |
   |---------------|
   | Result        |
4  |               |  LONG - result (if any)
   |---------------|
1  | RTL^3         |  3 BYTES - RTL address

Pascal syntax should look something like this:

function MyExtra(Data1: univ longint; UserID,CallNumber:integer): longint;

C syntax should look something like this:

pascal long MyExtra(long Data1, word UserID, word CallNumber)

Defined CallNumber values:

0 - azSaysInit   This is called after your external is loaded to give it a
    chance to allocate any additional memory needed or any other setup.
    The loword of the return parameter must be set according to Flags as
    defined below.  The loword of dataIn is set to AZ's version number.
    ($82xx for AudioZap 2.0bxx, 0200 for AudioZap 2.0 final). The hiword
    of dataIn is set to your Extra's refNum.  This is not currently needed for
    any calls, but may be in the future.

1 - azSaysShutDown  This is called at shutdown time so you may deallocate
    any memory you grabbed at azSaysInit time.

2 - azSaysIdle  This is called when the program is idle if your wantsIdle
    flag bit is set.  Data1 is the tick count when the user last did something,
    so you can write something which only trips when the user has not done
    anything for a few minutes.

3 - azSaysMenu  This is called when something is selected from one of AZ's
    own menus.  The loword of Data1 specifies which one.  This is only called
    if wantsAZMenus is set in your Flags.  Note that taking over the About,
    Open, Save, Save As, or Quit menu items is considered to be a Bad Thing.
    If you handled the menu set Result to $ffffffff, otherwise set it to 0.
    Note that all installed externals with the wantsAZMenus flag bit set will
    be given a chance to intercept the item.

4 - azSaysYourMenu  This is called when something is selected from a menu
    item which you added.  Data1 contains the item number.  Subtract the
    menu base you get at azSaysAddMenuTime to get which of your items from
    zero to (numItems-1).  (they will be in the order in the menu list).
    Note that you should not have to worry about getting an invalid item
    number, since AZ does range checking.
	
5 - azSaysUnknownFile   This is called if you are a File Type Parser as
    shown in your flags and an file with a type unknown to AZ's built-in
    parsers is selected with the Open menu command.  As with azSaysMenu,
    return $ffffffff (-1) if you parsed the file, otherwise 0.  Data1
    is a pointer to the Standard File new-style reply record as documented
    in Apple IIgs Toolbox Reference Volume 3.  At this point, the file has
    already been loaded into memory so you only need to look thru it (starting
    at RealPtr).  Return 0 in DataOut if you handled the file and 1 if you
    didn't.

6 - azSaysAddMenuTime   This is called when AZ's menubar is being built
    so that you may add menu items.  Data1 contains the menu base (ie the
    Menu Mgr item number of your first menu item) which you should save for
    use during azSaysYourMenu.  You should set the output Space to a pointer
    to the following menu list structure:
	
    WORD:  # of menu to insert this item in.  A zero terminates the list.
    LONG:  POINTER to menu item record as documented in Toolbox Reference 3.

    (this structure repeats until a zero for menu number is found so that
     you may easily insert more than one menu item in more than one menu).

    This is only called if hasMenuItems is set in Flags.

7 - azSaysTakeABow  This is called in the About procedure after AZ's own
    about box has been 'okay'-ed if you have wantsToTakeABow set in Flags.

8 - azSaysHelp  This is called if the user selects a menu item of yours
    while AZ is in Help mode and flag bit 10 is set to 1.  The loword of
    Data1 is set to the same menu item number used for azSaysYourMenu.

9 - azAsksFTName  This is called early on if your Extra is a File Type
    Parser with the canSave bit set.  The result should be a pointer to
    a Pascal string containing the name of the file type/format this
    Extra saves, such as "AIFF".

A - azSaysSave  This is called when it's time to save a file when your
    format is selected in the Format menu.

Codes B-FFFF are reserved and should be handled in a reasonable fashion.

The Flags word for AZ Extras
----------------------------

bit     what
------------
15      wantsAZMenus
14      hasMenuItems
13      fileTypeParser
12      wantsToTakeABow
11      wantsIdle
10      hasHelp
9       GNOAware
8       needsGNO
7       canSave
6-0    reserved, must be zero.

Notes:

Bits 15-10 are covered above.

Bits 8 and 9 were intended for GNO/ME compatibility, but are not used.

If bit 13 is set, bit 7 indicates if your Extra can save the format it loads.
(You will then get the azAsksFTName and azSaysSave messages).

AZ Menu Numbers
---------------

1 Apple
2 File
3 Edit
4 Sound
5 F/X
6 Format
7 Zoom

AZ Menu Item Numbers for azSaysMenu and tellAZMenu
--------------------------------------------------

Number         Internal Table           What
--------------------------------------------
dec  hex
256  100   	dc i2'DoAbout'	         About
257  101	dc i2'DoConfig'	         Configuration/Preferences
258  102	dc i2'DoNew'             New
259  103	dc i2'DoOpen'            Open
260  104	dc i2'JustSave'          Save
261  105	dc i2'DoSave'            SaveAs
262  106	dc i2'Revert'            Revert
263  107	dc i2'DoQuit'            Quit
264  108        dc i2'Ignore'	         Transfer
265  109	dc i2'GetDOCData'        Open DOC Data
266  10A	dc i2'OpenDisk'          Open Disk
267  10B	dc i2'DoDelete'          Delete file
268  10C	dc i2'DoFormat'          Format Disk
269  10D	dc i2'ClearClip'         Clear Clipboard
270  10E	dc i2'LoadToSelect'      Load to Selection Point
271  10F	dc i2'DoIsolate'         Isolate Selection
272  110	dc i2'DoDigitize'        Record
273  111        dc i2'Ignore'            reserved
274  112	dc i2'DoHQPlay'          Play
275  113	dc i2'ShutUp'            Stop
276  114	dc i2'DoOsc'             Oscilloscope
277  115	dc i2'MonInput'          Input Monitor
278  116	dc i2'SBSetup'           Setup Card
279  117	dc i2'DoSilence'	 Silence
280  118	dc i2'DoReverse'	 Backwards
281  119	dc i2'DoMetal'	         Cruncher
282  11A	dc i2'DoLayer'           Layer
283  11B	dc i2'FreqUp'	         Freq. up
284  11C	dc i2'GSToAmy'           GS<->Amiga
285  11D	dc i2'FilterZeros2'      FilterZeroes
286  11E	dc i2'DoAmplify'         Amplify
287  11F	dc i2'DoNorm'            Normalize
288  120	dc i2'Compact'           Compact
289  121        dc i2'Ignore'            Reserved
290  122        dc i2'Ignore'            "
291  123        dc i2'Ignore'            "
292  124        dc i2'Ignore'            "	
293  125        dc i2'Ignore'            "
294  126        dc i2'Ignore'            "
295  127        dc i2'Ignore'            "
296  128        dc i2'Ignore'            "
297  129        dc i2'Ignore'            "
298  12A        dc i2'Ignore'            "
299  12B        dc i2'Ignore'            "
300  12C        dc i2'Ignore'            "
301  12D        dc i2'Ignore'            "
302  12E        dc i2'Ignore'            "
303  12F        dc i2'Ignore'            "
304  130        dc i2'ZoomIn'            Zoom In
305  131	dc i2'ZoomOut'	         Zoom Out
306  132	dc i2'FullLook'	         Full View
307  133	dc i2'Append'            Append
	
Menu items numbered from $1000 and up are Format menu items.  Don't create
your own in that range.

AZ Direct Page map
------------------
Note: be very careful when using AZ's direct page.  Invalid values for many
locations can cause fun and exciting crashes.

Locs $00 - $1F are free for your use.  However they are also free for the
use of other externals and AZ itself so don't count on them as permanent
storage.

Locs $20 - $4F are reserved for future use by AudioZap.

AZ's label	where	comment	
----------------------------------------------------------------------------

StartStopRef	gequ $50	; Returned by StartUpTools
MyMID	        gequ $54        ; Master ID
MyID	        gequ $56      	; User ID
HandToData	gequ $58      	; Handle to wave buffer
PtrToData 	gequ $5C        ; POINTER to end of waveform
EndOfData 	gequ $60        ; LENGTH of wave buffer in bytes
Reserved 	gequ $64        ; reserved for future use
IRQOsc	        gequ $66        ; Oscillator that interrupted last
BTR	        gequ $67        ; Banksel/tablesize/resolution
RealPtr	        gequ $68     	; POINTER to beginning of wave buffer
SRate	        gequ $6C        ; Sampling rate
End	        gequ $70       	; POINTER to end of data area
ChangeFl	gequ $74      	; BOOLEAN:Wave changed since load/digi?
PRate	        gequ $76        ; Playback rate in Ensoniq units
SHand1	        gequ $7A       	; Handle to first scroll bar
SHand2	        gequ $7E     	; Handle to second scroll bar
WPort	        gequ $80       	; GrafPort pointer of main window
Rpt	        gequ $84      	; BOOLEAN: loop playback flag
EdLoc	        gequ $86    	; POINTER to beginning of selection
EdEnd	        gequ $8A      	; POINTER to end of selection range
Temp0	        gequ $8E      	; Temporary storage; open for use
Playing	        gequ $92      	; BOOLEAN: is sound playing?
WaveInc	        gequ $94       	; Bytes per pixel in graph of sound
Card	        gequ $98        ; Card type
Slot	        gequ $9A   	; Slot of card (in the form $Cs0x)
EdMin	        gequ $9C   	; Left edge of selection range
EdMax	        gequ $9E    	; Right edge of selection range
SelectValid	gequ $A0    	; Selection valid flag
EdSize	        gequ $A4    	; Selection length
PlayPtr	        gequ $A8     	; reserved
PlayEnd	        gequ $AC        ;    "
ClipPtr	        gequ $B0        ; Clipboard POINTER
PlayPtr2	gequ $B4        ; reserved
IconHand	gequ $B8        ; HANDLE to help icon
CursHand	gequ $BC        ; HANDLE to help cursor
HelpFlag	gequ $C0        ; BOOLEAN: true if in help mode
ThermHand	gequ $C2        ; HANDLE to play thermometer control
NDAFlag	        gequ $C6	; BOOLEAN: see below

Card types are:
0 - SuperSonic
1 - Sonic Blaster
2 - HyperStudio
3 - Audio Animator
|4 - Mac-style serial port digitizer
|5 - SoundMeister
|6 - MDI Digitizer Pro

Locations $BA - $FF are reserved for use by AudioZap.

You will probably be most interested in RealPtr which points to the beginning
of the wave buffer, PtrToData which points to the end of the waveform, and
End which points to the end of the wave buffer.  Note that the clipboard is
allocated from the end of the wave buffer, so if you need to grow the wave
you should check if ClipPtr is nonzero and avoid colliding with it if so.
If ClipPtr is zero, you have (End-PtrToData) bytes avalible in the wave
buffer: otherwise it is (ClipPtr-PtrOfData).

If you are putting up a window for some reason, you should save NDAFlag, set
it to any nonzero value, and restore it when you are done.  This prevents
AZ from redrawing the sound wave with the screen slammer; QuickDraw is used
in that case to prevent unwanted effects.  If your window is not movable you
also can skirt the issue by not allowing windows other than your own to be
updated.

Tools Started by AudioZap
-------------------------

You can assume all the tools listed below to be started.  Any others you will
need to start and shutdown yourself.  In addition, QuickDraw is started up
with FastPort and Shadowing enabled.
	
   Tool Locator
   Memory Manager
   Misc Tools
   QuickDraw II
   Desk Manager
   Event Manager
   Sound Tools *
   SANE
   Window Manager
   Menu Manager
   Control Manager
   QuickDraw II Aux
   LineEdit Manager
   Dialog Manager
   Standard File
   Scrap Manager
   Font Manager
   ACE Tools
   Resource Manager
   TextEdit

* The Sound Tools MIRQV is not in effect, so _FFStartSound or _FFStartPlaying
  will likely cause system failure.  Do a _SendRequest with the code
  tellAZPlayThis instead.

AZ Extras as INITs
------------------

There is a second way to write an AZ Extra, which is as part of an INIT using
the System 6.0 IAC facility.  To use this, simply install a request acceptor
and look for request ID $8100, azSaysWakeUp.  This is sent out immediately
after AZ is loaded, but before the Extras get azSaysInit.  Once you get this
message you should send request $8000, tellAZInstallMe, with DataIn set as
a pointer to your Extra as shown above.  The only difference between an
Extra installed in this fashion and a normal AZExtras/ one is that an INIT
based Extra has its own ID assigned at boot time so AZ passes $FFFF for your
ID during calls to reflect this.  Note that this mechanism also makes it
possible for EXE Extras to add additional Extras contained within themselves.

Talking Back to AZ
------------------
		
Here are all the tellAZ codes currently defined.  AZ's request procedure
name is "Cygnix~AudioZap~" (without the quotes of course).  All tellAZ and
askAZ codes should thus be sent to Cygnix~AudioZap~.  tellAZ and askAZ
requests can of course be sent from both normal and INIT-based Extras.

| Note: functions set off with bars like this aren't implemented yet.
| Don't try to call them :)
|


$8000    tellAZInstallMe     Install what DataIn points to as an AZ Extra.
	
	
|$8001    tellAZPlayThis      Tell AZ to play a sound, since FFStartSound
|	              will cause a system death while AudioZap is 
|	              running.  This request will be rejected if
|	              AudioZap is currently playing a sound either
|	              due to the user selecting play or a previous
|	              unfinished tellAZPlayThis request.  Playback
|	              will always be in stereo on channels 0 and 1.
|	              DataIn points to this structure:
 __________________	
|                  |
|   Rate           |  WORD - standard Ensoniq frequency, same as FFStartSound
|__________________|
|                  |
|   Pointer to     |  LONG - points to wave data
|    wave          |
|__________________|
|                  |
|  Length (bytes)  |  LONG - length of sound in bytes
|                  |
|__________________|
|                  |
|  Volume          |  WORD - standard Ensoniq volume, 0-255 are valid
|__________________|

$8002    tellAZQuit          Causes AudioZap to exit next time its event
          	             loop gains control.

|$8003    tellAZLaunchThis    Causes AudioZap to exit, and launch the
|	              application whose path is pointed to by Data1.

|$8004    tellAZRefresh       Causes AudioZap to redraw the main window
|	              and its contents.

|$8005    tellAZMenu          Causes AudioZap to execute the menu item in
|	              the lo word of dataIn (see Menu Item Reference
|	              above).

|$8006    tellAZSetPRate      Causes AudioZap to set the play rate to the
|                            low-level Ensoniq frequency in the loword of
|	              DataIn.

|$8007    tellAZOpenThis      Causes AudioZap to open a file.  DataIn points
|	              to a GS/OS string containing the pathname.
	
|$8008    tellAZSetAccel      Causes AudioZap to turn a ZipGS or TransWarp GS
|	              on or off if one is present.  If none is present
|	              no harm is done.  DataIn is 0 for accel. off and
|	              any non-zero value to turn the accel. on.

$8009    askAZdirectPage     DataOut is returned as a LONG pointer to AZ's
                             direct page for the convience of those writing
	              Extras in C or Pascal.
	
$800A    askAZareYouThere    DataOut is returned as 4 ASCII characters "CDAZ"
                             (AZ in the hi word, CD in the lo) if AudioZap 2.0
                             is present.  This is a good defense against non-AZ
                             programs using the $8100 azSaysWakeUp code.
	
$800B    tellAZInitTherm     Puts up AZ's built-in thermometer window.  DataIn
                             points to a structure; the first word is the
                             thermometer DataSize, the second is the ViewSize,
                             and then there is a pointer to a Pascal string
                             to put above the thermometer.

$800C    tellAZSetTherm      The low word of DataIn is the value to set the
                             thermometer to, from 0 to DataSize.

$800D    tellAZCloseTherm    Closes the thermometer window.  You may also
                             CloseWindow(FrontWindow()); safely.

Codes $800E-$FFFF when sent to "Cygnix~AudioZap~" are reserved.

|AudioZap also accepts system code $0006, srqPlayrSoundSample, so that the
|Sound Control Panel continues to function while AZ is running.

What AZ Says
------------

code     name                comments
							
$8100    azSaysWakeUp        DataIn and DataOut are reserved.  This is sent
                             while AZ initializes so that Extras which also
	                     do other stuff can be recognized (I certainly
	                     would like to discourage you from writing an INIT
	                     which only is useful for AudioZap.  That would
                             waste memory.)  It is reasonable to call
	                     tellAZInstallMe at this time; other codes	
	                     will probably crash the system.
